let rustdoc print the crate version into docs #44989

QuietMisdreavus · 2017-10-02T23:40:12Z

This PR adds a new unstable flag to rustdoc, --crate-version, which when present will add a new entry to the sidebar of the root module, printing the given version number:

Closes #24336

(The WIP status is because i don't want to merge this until i can get the std docs to use it, which i need help from rustbuild people to make sure i get right.)

rust-highfive · 2017-10-02T23:40:15Z

Some changes occurred in HTML/CSS.

cc @GuillaumeGomez

rust-highfive · 2017-10-02T23:40:17Z

r? @steveklabnik

(rust_highfive has picked a reviewer for you, use r? to override)

QuietMisdreavus · 2017-10-02T23:44:18Z

Pings for everyone!

@rust-lang/docs Does this look right? Is this a good place for this? Right now it only shows up on the root module's page - nothing else will show this. Should we put it everywhere?

@GuillaumeGomez and @steveklabnik specifically (possibly dev-tools more broadly, but for now i'll stick with rustdoc peers) - This is a new command-line flag. In dev-tools meeting today the prevailing air was that this was not RFC worthy since it was straightforward enough, but i want to make extra sure that the other rustdoc stakeholders are on board.

@alexcrichton @Mark-Simulacrum (other rustbuild experts?) - How can I get bootstrap to use this flag when rendering docs for std and friends?

GuillaumeGomez · 2017-10-03T08:03:19Z

Seems to be good. What happens with a very long version name? Does it goes on two lines or does it just stick out of the sidebar?

QuietMisdreavus · 2017-10-03T13:08:59Z

Looks like it wraps within the sidebar:

...unless you use a long word without a breaking separator, in which case it sticks out from the sidebar:

GuillaumeGomez · 2017-10-03T22:22:10Z

This is a (smaaall) bug then. :p

steveklabnik · 2017-10-05T12:16:29Z

This sounds good to me!

camsteffen · 2017-10-09T01:29:51Z

Use these styles to fix the wrapping issue on most modern browsers.

overflow-wrap: break-word;
word-wrap: break-word; /* deprecated */
word-break: break-word; /* Chrome, non-standard */

QuietMisdreavus · 2017-10-09T14:57:44Z

Wow, thanks! That looks much better!

I've force-pushed to include that CSS into the update.

GuillaumeGomez · 2017-10-09T15:47:41Z

Now it's all good. Thanks!

@bors: r+ rollup

bors · 2017-10-09T15:47:42Z

📋 Looks like this PR is still in progress, ignoring approval

GuillaumeGomez · 2017-10-09T15:49:00Z

Ah damn, well, r=me once done.

QuietMisdreavus · 2017-10-09T15:54:39Z

Yeah, the rustdoc piece is basically done, but i'd like to see if i can get rustbuild to use this when generating the docs for std and friends before calling it done. I'll ask around again.

Mark-Simulacrum · 2017-10-09T17:22:59Z

You'll need to edit src/bootstrap/builder.rs and add RUSTDOC_CRATE_VERSION to the rustdoc_cmd environment variables. The value can be pulled from channel::CFG_RELEASE_NUM (1.22.0) or if you want the SHA, self.build.rust_info.version(...) will work.

Let me know if you'd like more detailed instructions, or I can probably get you a commit implementing this within a few days.

QuietMisdreavus · 2017-10-09T20:26:05Z

@Mark-Simulacrum That got me most of the way there. It turns out that the docs weren't using rustdoc_cmd at all, instead going through cargo. I wound up adding RUSTDOCFLAGS to each doc invocation to get the crate version in, but that can introduce problems in compiler-docs mode, since external crates will also get that version number. I also don't know how this will interact if/when Cargo starts providing this flag itself, but for the moment this does what i want:

If you think this is fine, then i'm ready to call this good.

Mark-Simulacrum · 2017-10-09T23:40:54Z

Hm, I'm suspecting that RUSTDOCFLAGS may not apply correctly with compiler docs, since we want the version to display on more than just the last crate. I think I'd move to unconditionally setting something like RUSTDOC_CRATE_VERSION in cargo (src/bootstrap/builder.rs) and then using that in src/bin/rustdoc.rs to set the unstable option.

QuietMisdreavus · 2017-10-10T00:24:42Z

Ooh, i like that option. I've force-pushed with an update that uses that instead.

Mark-Simulacrum

I'm happy with the rustbuild changes after this small nit.

Mark-Simulacrum · 2017-10-10T23:35:03Z

src/bootstrap/builder.rs

@@ -574,6 +574,9 @@ impl<'a> Builder<'a> {
            cargo.env("RUSTC_SAVE_ANALYSIS", "api".to_string());
        }

+        // For `cargo doc` invocations, make rustdoc print the Rust version into the docs
+        cargo.env("RUSTDOC_CRATE_VERSION", self.build.rust_version());


Let's also add this to rustdoc_cmd above to make certain it's passed in all cases.

Force-pushed with this update.

Mark-Simulacrum · 2017-10-11T20:40:37Z

@bors r=GuillaumeGomez

bors · 2017-10-11T20:40:38Z

📌 Commit 7ea286e has been approved by GuillaumeGomez

… r=GuillaumeGomez let rustdoc print the crate version into docs This PR adds a new unstable flag to rustdoc, `--crate-version`, which when present will add a new entry to the sidebar of the root module, printing the given version number: ![Screenshot of a test crate, showing "Version 1.3.37" under the crate name](https://user-images.githubusercontent.com/5217170/31104096-805e3f4c-a7a0-11e7-96fc-368b6fe063d6.png) Closes rust-lang#24336 (The WIP status is because i don't want to merge this until i can get the std docs to use it, which i need help from rustbuild people to make sure i get right.)

[WIP] Rollup of 10 pull requests - Successful merges: #44989, #45005, #45049, #45105, #45121, #45163, #45166, #45172, #45190, #45231 - Failed merges: #45138

Rollup of 9 pull requests - Successful merges: #44989, #45005, #45049, #45105, #45121, #45166, #45172, #45190, #45231 - Failed merges: #45138

rust-highfive assigned steveklabnik Oct 2, 2017

QuietMisdreavus mentioned this pull request Oct 2, 2017

Show library version in documentation generated by rustdoc #24336

Closed

shepmaster added the S-waiting-on-author Status: This is awaiting some action (such as code changes or more information) from the author. label Oct 6, 2017

let rustdoc print the crate version into docs

fcee950

QuietMisdreavus force-pushed the what-is-your-quest branch from 8cdaec5 to fcee950 Compare October 9, 2017 14:56

QuietMisdreavus changed the title ~~[WIP] let rustdoc print the crate version into docs~~ let rustdoc print the crate version into docs Oct 9, 2017

QuietMisdreavus force-pushed the what-is-your-quest branch from b0b746c to ce71c9e Compare October 9, 2017 20:35

QuietMisdreavus force-pushed the what-is-your-quest branch 3 times, most recently from 21cb80a to 5a847c6 Compare October 10, 2017 00:23

Mark-Simulacrum reviewed Oct 10, 2017

View reviewed changes

render the rust version into std/compiler/test docs

7ea286e

QuietMisdreavus force-pushed the what-is-your-quest branch from 5a847c6 to 7ea286e Compare October 11, 2017 01:36

kennytm mentioned this pull request Oct 12, 2017

Rollup of 9 pull requests #45233

Merged

bors added a commit that referenced this pull request Oct 12, 2017

Auto merge of #45233 - kennytm:rollup, r=<try>

6f8b325

[WIP] Rollup of 10 pull requests - Successful merges: #44989, #45005, #45049, #45105, #45121, #45163, #45166, #45172, #45190, #45231 - Failed merges: #45138

bors added a commit that referenced this pull request Oct 12, 2017

Auto merge of #45233 - kennytm:rollup, r=kennytm

64ee7d1

Rollup of 9 pull requests - Successful merges: #44989, #45005, #45049, #45105, #45121, #45166, #45172, #45190, #45231 - Failed merges: #45138

bors merged commit 7ea286e into rust-lang:master Oct 13, 2017

QuietMisdreavus deleted the what-is-your-quest branch October 13, 2017 01:38

aleksator mentioned this pull request Feb 19, 2020

Insert package name/version in API docs rust-lang/cargo#1681

Closed

let rustdoc print the crate version into docs #44989

let rustdoc print the crate version into docs #44989

Uh oh!

Conversation

QuietMisdreavus commented Oct 2, 2017 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

rust-highfive commented Oct 2, 2017

Uh oh!

rust-highfive commented Oct 2, 2017

Uh oh!

QuietMisdreavus commented Oct 2, 2017 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

GuillaumeGomez commented Oct 3, 2017

Uh oh!

QuietMisdreavus commented Oct 3, 2017

Uh oh!

GuillaumeGomez commented Oct 3, 2017

Uh oh!

steveklabnik commented Oct 5, 2017

Uh oh!

camsteffen commented Oct 9, 2017

Uh oh!

QuietMisdreavus commented Oct 9, 2017

Uh oh!

GuillaumeGomez commented Oct 9, 2017

Uh oh!

bors commented Oct 9, 2017

Uh oh!

GuillaumeGomez commented Oct 9, 2017

Uh oh!

QuietMisdreavus commented Oct 9, 2017

Uh oh!

Mark-Simulacrum commented Oct 9, 2017

Uh oh!

QuietMisdreavus commented Oct 9, 2017

Uh oh!

Mark-Simulacrum commented Oct 9, 2017

Uh oh!

QuietMisdreavus commented Oct 10, 2017

Uh oh!

Mark-Simulacrum left a comment

Choose a reason for hiding this comment

Uh oh!

Mark-Simulacrum Oct 10, 2017

Choose a reason for hiding this comment

Uh oh!

QuietMisdreavus Oct 11, 2017

Choose a reason for hiding this comment

Uh oh!

Mark-Simulacrum commented Oct 11, 2017

Uh oh!

bors commented Oct 11, 2017

Uh oh!

Uh oh!

QuietMisdreavus commented Oct 2, 2017 •

edited

Loading

QuietMisdreavus commented Oct 2, 2017 •

edited

Loading